home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / catD / rmalloc.z / rmalloc
Encoding:
Text File  |  1998-10-30  |  11.4 KB  |  197 lines
  1.  
  2.  
  3.  
  4. rrrrmmmmaaaalllllllloooocccc((((DDDD3333))))                                                        rrrrmmmmaaaalllllllloooocccc((((DDDD3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _rrrr_mmmm_aaaa_llll_llll_oooo_cccc - allocate space from a private space management map
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_mmmm_aaaa_pppp_...._hhhh_>>>>
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_dddd_dddd_iiii_...._hhhh_>>>>
  15.      _uuuu_llll_oooo_nnnn_gggg______tttt _rrrr_mmmm_aaaa_llll_llll_oooo_cccc_((((_ssss_tttt_rrrr_uuuu_cccc_tttt _mmmm_aaaa_pppp _****_m_p_,,,, _ssss_iiii_zzzz_eeee______tttt _s_i_z_e_))))_;;;;
  16.  
  17.    AAAArrrrgggguuuummmmeeeennnnttttssss
  18.      _m_p        Pointer to the map from which space is to be allocated.
  19.  
  20.      _s_i_z_e      Number of units of space to allocate.
  21.  
  22. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  23.      _rrrr_mmmm_aaaa_llll_llll_oooo_cccc allocates space from the private space management map pointed to
  24.      by _m_p.
  25.  
  26.    RRRReeeettttuuuurrrrnnnn VVVVaaaalllluuuueeeessss
  27.      Upon successful completion, _rrrr_mmmm_aaaa_llll_llll_oooo_cccc returns the base of the allocated
  28.      space.  If _s_i_z_e units cannot be allocated, 0 is returned.
  29.  
  30. UUUUSSSSAAAAGGGGEEEE
  31.      Drivers can use _rrrr_mmmm_aaaa_llll_llll_oooo_cccc to allocate space from a previously allocated and
  32.      initialized private space management map.
  33.  
  34.      The map must have been allocated by a call to _rrrr_mmmm_aaaa_llll_llll_oooo_cccc_mmmm_aaaa_pppp(D3) and the
  35.      space managed by the map must have been added using _rrrr_mmmm_ffff_rrrr_eeee_eeee(D3) prior to
  36.      the first call to _rrrr_mmmm_aaaa_llll_llll_oooo_cccc for the map.
  37.  
  38.      _s_i_z_e specifies the amount of space to allocate and is in arbitrary units.
  39.      The driver using the map places whatever semantics on the units are
  40.      appropriate for the type of space being managed.  For example, units may
  41.      be byte addresses, pages of memory, or blocks on a device.
  42.  
  43.      The system allocates space from the memory map on a first-fit basis and
  44.      coalesces adjacent space fragments when space is returned to the map by
  45.      _rrrr_mmmm_ffff_rrrr_eeee_eeee.
  46.  
  47.    LLLLeeeevvvveeeellll
  48.      Initialization, Base or Interrupt.
  49.  
  50.    SSSSyyyynnnncccchhhhrrrroooonnnniiiizzzzaaaattttiiiioooonnnn CCCCoooonnnnssssttttrrrraaaaiiiinnnnttttssss
  51.      Does not sleep.
  52.  
  53.      Driver-defined basic locks, read/write locks, and sleep locks may be held
  54.      across calls to this function.
  55.  
  56.    EEEExxxxaaaammmmpppplllleeeessss
  57.      The following example is a simple memory map, but it illustrates the
  58.      principles of map management.  A driver declares a map table (line 4) and
  59.      initializes the map table by calling the _rrrr_mmmm_ffff_rrrr_eeee_eeee function.  There are 35
  60.  
  61.  
  62.                                                                         PPPPaaaaggggeeee 1111
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69. rrrrmmmmaaaalllllllloooocccc((((DDDD3333))))                                                        rrrrmmmmaaaalllllllloooocccc((((DDDD3333))))
  70.  
  71.  
  72.  
  73.      entries in the map table, 32 of which can be used to represent space
  74.      allocated.  In the driver's _ssss_tttt_aaaa_rrrr_tttt(D2) routine, we allocate 16 Kbytes of
  75.      memory using _rrrr_mmmm_aaaa_llll_llll_oooo_cccc_mmmm_aaaa_pppp(D3) (line 8).  This is the space to be managed.
  76.      Then call _rrrr_mmmm_ffff_rrrr_eeee_eeee to populate the map with the space it is to manage (line
  77.      10).
  78.  
  79.      In the driver's _rrrr_eeee_aaaa_dddd(D2) and _wwww_rrrr_iiii_tttt_eeee(D2) routines, we use _rrrr_mmmm_aaaa_llll_llll_oooo_cccc to
  80.      allocate buffers for data transfer.  This example illustrates the _wwww_rrrr_iiii_tttt_eeee
  81.      routine.  Assuming the device can only transfer _XXXX_XXXX______MMMM_AAAA_XXXX_BBBB_UUUU_FFFF_SSSS_ZZZZ bytes at a
  82.      time, we calculate the amount of data to copy (line 21) and use _rrrr_mmmm_aaaa_llll_llll_oooo_cccc
  83.      to allocate some space from the map.  The call to _rrrr_mmmm_aaaa_llll_llll_oooo_cccc is protected
  84.      against interrupts (line 22) from the device that may result in freeing
  85.      map space.  This way, if space is freed, we won't miss the corresponding
  86.      _wwww_aaaa_kkkk_eeee_uuuu_pppp(D3).
  87.  
  88.       _1111  _####_dddd_eeee_ffff_iiii_nnnn_eeee _XXXX_XXXX______MMMM_AAAA_PPPP_SSSS_IIII_ZZZZ_EEEE   _3333_5555
  89.       _2222  _####_dddd_eeee_ffff_iiii_nnnn_eeee _XXXX_XXXX______MMMM_EEEE_MMMM_SSSS_IIII_ZZZZ_EEEE   _((((_1111_6666_****_1111_0000_2222_4444_))))
  90.       _3333  _####_dddd_eeee_ffff_iiii_nnnn_eeee _XXXX_XXXX______MMMM_AAAA_XXXX_BBBB_UUUU_FFFF_SSSS_ZZZZ  _1111_0000_2222_4444
  91.       _4444  _ssss_tttt_rrrr_uuuu_cccc_tttt _mmmm_aaaa_pppp _****_xxxx_xxxx______mmmm_aaaa_pppp_;;;;
  92.          _...._...._....
  93.       _5555  _xxxx_xxxx______ssss_tttt_aaaa_rrrr_tttt_((((_))))
  94.       _6666  _{{{{
  95.       _7777    _cccc_aaaa_dddd_dddd_rrrr______tttt _bbbb_pppp_;;;;
  96.       _8888    _iiii_ffff _((((_((((_mmmm_pppp_====_rrrr_mmmm_aaaa_llll_llll_oooo_cccc_mmmm_aaaa_pppp_((((_xxxx_xxxx______MMMM_AAAA_PPPP_SSSS_IIII_ZZZZ_EEEE_)))) _====_==== _0000
  97.       _9999         _cccc_mmmm_nnnn______eeee_rrrr_rrrr _((((_CCCC_EEEE______PPPP_AAAA_NNNN_IIII_CCCC_,,,, _""""_xxxx_xxxx______ssss_tttt_aaaa_rrrr_tttt_:::: _cccc_oooo_uuuu_llll_dddd _nnnn_oooo_tttt _aaaa_llll_llll_oooo_cccc_aaaa_tttt_eeee _mmmm_aaaa_pppp_""""_))))_;;;;
  98.      _1111_0000    _rrrr_mmmm_ffff_rrrr_eeee_eeee_((((_xxxx_xxxx______mmmm_aaaa_pppp_,,,, _XXXX_XXXX______MMMM_EEEE_MMMM_SSSS_IIII_ZZZZ_EEEE_,,,, _bbbb_pppp_))))_;;;;
  99.      _1111_1111  _}}}}
  100.          _...._...._....
  101.      _1111_2222  _xxxx_xxxx______wwww_rrrr_iiii_tttt_eeee_((((_dddd_eeee_vvvv_,,,, _uuuu_iiii_oooo_pppp_,,,, _cccc_rrrr_pppp_))))
  102.      _1111_3333    _dddd_eeee_vvvv______tttt _dddd_eeee_vvvv_;;;;
  103.      _1111_4444    _uuuu_iiii_oooo______tttt _****_uuuu_iiii_oooo_pppp_;;;;
  104.      _1111_5555    _cccc_rrrr_eeee_dddd______tttt _****_cccc_rrrr_pppp_;;;;
  105.      _1111_6666  _{{{{
  106.      _1111_7777    _cccc_aaaa_dddd_dddd_rrrr______tttt _aaaa_dddd_dddd_rrrr_;;;;
  107.      _1111_8888    _ssss_iiii_zzzz_eeee______tttt _ssss_iiii_zzzz_eeee_;;;;
  108.      _1111_9999    _iiii_nnnn_tttt _ssss_;;;;
  109.          _...._...._....
  110.      _2222_0000    _wwww_hhhh_iiii_llll_eeee _((((_uuuu_iiii_oooo_pppp_----_>>>>_uuuu_iiii_oooo______rrrr_eeee_ssss_iiii_dddd _>>>> _0000_)))) _{{{{
  111.      _2222_1111        _ssss_iiii_zzzz_eeee _==== _mmmm_iiii_nnnn_((((_uuuu_iiii_oooo_pppp_----_>>>>_uuuu_iiii_oooo______rrrr_eeee_ssss_iiii_dddd_,,,, _XXXX_XXXX______MMMM_AAAA_XXXX_BBBB_UUUU_FFFF_SSSS_ZZZZ_))))_;;;;
  112.      _2222_2222        _ssss _==== _ssss_pppp_llll_4444_((((_))))_;;;;
  113.      _2222_3333        _wwww_hhhh_iiii_llll_eeee _((((_((((_aaaa_dddd_dddd_rrrr _==== _((((_cccc_aaaa_dddd_dddd_rrrr______tttt_))))_rrrr_mmmm_aaaa_llll_llll_oooo_cccc_((((_xxxx_xxxx______mmmm_aaaa_pppp_,,,, _ssss_iiii_zzzz_eeee_))))_)))) _====_==== _NNNN_UUUU_LLLL_LLLL_)))) _{{{{
  114.      _2222_4444            _ssss_llll_eeee_eeee_pppp_((((_((((_cccc_aaaa_dddd_dddd_rrrr______tttt_))))_xxxx_xxxx______mmmm_aaaa_pppp_,,,, _PPPP_ZZZZ_EEEE_RRRR_OOOO_))))_;;;;
  115.      _2222_5555        _}}}}
  116.      _2222_6666
  117.      _2222_7777        _ssss_pppp_llll_xxxx_((((_ssss_))))_;;;;
  118.                _...._...._....
  119.      _2222_8888    _}}}}
  120.          _...._...._....
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.                                                                         PPPPaaaaggggeeee 2222
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134. rrrrmmmmaaaalllllllloooocccc((((DDDD3333))))                                                        rrrrmmmmaaaalllllllloooocccc((((DDDD3333))))
  135.  
  136.  
  137.  
  138. RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS
  139.      _rrrr_mmmm_aaaa_llll_llll_oooo_cccc______wwww_aaaa_iiii_tttt(D3), _rrrr_mmmm_aaaa_llll_llll_oooo_cccc_mmmm_aaaa_pppp(D3), _rrrr_mmmm_ffff_rrrr_eeee_eeee(D3), _rrrr_mmmm_ffff_rrrr_eeee_eeee_mmmm_aaaa_pppp(D3),
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.                                                                         PPPPaaaaggggeeee 3333
  194.  
  195.  
  196.  
  197.